Layout automation with python

Thomas Ferreira de Lima

Lightwave Lab, Princeton University

Oct 31st, 2019

https://github.com/thomaslima/2019-siepic-workshop-zeropdk

Email: tlima@princeton.edu

Outline

  • Motivation for procedural layout
  • Basic definitions
  • Tool requirements
    • KLayout
    • Python/Docker
  • An overview of Zeropdk
  • Demo preparation
  • Using SiEPIC with Zeropdk
    • Demo 1: Using SiEPIC cell library
  • Hierarchical layout
    • Demo 2: MZI PCell
  • Advanced layout techniques:
    • Geometry unit testing (lytest)
    • Visual debugging (lyipc)
    • Version control and collaboration
    • Outlook (help needed with DRC, SiEPIC and docs)

Motivation for procedural layout

  • GDSII is the industry standard file format for IC layout.
  • It organizes geometry in polygons, cells, and cell references.
  • However, it is quasi-binary: understood by machines, useless to humans.
  • There is no support for parameters, design intent, comments, connectivity, physical data.
  • Poor representation of curves

GDS has problems with curves

image.png

GDS does not capture logical relation

image.png

image.png

Procedural vs. Computer-aided

  • Computer-aided layout

    • Interactive: designer sees what’s happening at all times
    • Intuitive
    • No software bugs
    • Macros: some benefits of procedural
  • Procedural layout

    • Completely repeatable
    • Easy to apply global changes
    • Easy to version a chip, not just a library
    • Full record of design intent

IC design “by hand”, aided A LOT by computer

image.png

Procedural IC design today

image.png

What is new?

  • Photonic integration
  • High-level languages (Python)
  • Free software infrastructure

Difference with macros

  • Procedural means 100% coded
  • Push a button, GDS comes out
  • This means entire chips are defined 100% by source code
    • repeatable
    • human understandable
    • arbitrarily complex
    • more easily version controlled

Example from one of our chips

# make_chip.py

FLOORPLAN_SAFE = 50
TECHNOLOGY = TECHNOLOGY.layers  # TODO refactor

if __name__ == "__main__":
    layout = pya.Layout()
    dbu = layout.dbu = 0.001
    TOP = layout.create_cell("TOP")

    origin = pya.DPoint(0, 0)
    ex = pya.DVector(1, 0)
    ey = rotate90(ex)

    # FLOORPLAN
    FX, FY = 7850, 3000  # um
    layout_box(TOP, layout.layer(TECHNOLOGY["FloorPlan"]), 
               origin, origin + FX * ex + FY * ey, ex)

    # Placing each experiment
    placement_list = {
        "FeedbackWeightBank_experiment": (
            exp.FeedbackWeightBank_experiment, # PCell class
            2792.04000, 328.87000,             # position
            {"angle_ex": 90, "N": 5},          # parameters
        ),
    # ...
    }

    # Place all PCells in placement_list and export port locations for routing
    for name, (klass, x, y, params) in placement_list.items():
        exp_ports[name] = klass(name, params=params).place_cell(
                TOP, x * ex + y * ey
            )
    # ...

    # Perform routing using exp_ports dictionary
    # ...

    # Removing the $$$CONTEXT_INFO$$$ top cell (Foundries don't like it)

    save_options = pya.SaveLayoutOptions()
    save_options.write_context_info = False

    # CMC told us to have maximum cell name length of 60 characters
    save_options.gds2_max_cellname_length = 60

    layout.write("mpw-chip.gds", save_options)

Basic definitions

PCells

PCells are the foundation of layouts with more than a couple polygons

  • Rule of thumb: one pcell per device
  • Defined by code (logic) instead of points (geometry)
  • Reused to create many different geometries
  • Easy to edit
  • Can be nested

Routing elements

Routing elements refer to the connections between devices (drawn in PCells). They could be metal traces, optical waveguides, or I/O elements.

Ports

The connection between PCells and routing elements are defined in the concept of Ports. The port must contain information on the type of connection, the dimensions of the routing elemenet (e.g. waveguide width), a human-readable name, and positioning.

Tool Requirements

  • KLayout
  • Python modules:
    • klayout
    • zeropdk

KLayout

image.png

KLayout scripting

You probably all know KLayout, but few people make good use of the scripting documentation:

  • klayout.de » Documentation » Programming Scripts (recommend reading Database API and Geometry API)
  • klayout.de » Documentation » Reference (have it open while coding)

image.png

Python (klayout)

I helped Matthias to release a klayout package in PyPI. It works in a standalone way and is loaded with the Database and Geometry APIs, but not Application or Qt (yet).

pip install klayout

Currently there are pre-built wheels in the following versions:

OS Python Version
macOS 10.11+ 2.7, 3.7
macOS 10.13+ 3.5, 3.6
linux x64, x32 2.7, 3.5, 3.6, 3.6
win32, win64 3.5, 3.6, 3.7

Note for advanced users: You can attempt to build klayout from source by running python setup.py install on the cloned folder from klayout's github repo.

In [2]:
!pip install klayout

import klayout.db as pya

a = pya.DPoint(1, 2)
b = pya.DVector(0, 1)

a+b
Requirement already satisfied: klayout in /Users/tlima/Envs/zeropdk37/lib/python3.7/site-packages (0.26.0.dev16)
Out[2]:
1,3

Python (zeropdk)

Our lab relies on klayout's database engine to produce masks for MPW manufacturing. To aid collaboration, we open-sourced a tool called zeropdk.

Many foundries only offer PDKs to commercial software with a steep price tag, but are happy to offer libraries of standard components in the .gds format. ZeroPDK allows you to quickly bootstrap a Photonics PDK without necessarily relying on their partners: great for academic users and students. Also great for pro users.

Zeropdk is available with pip install zeropdk and the source code is released in our github page

An overview of Zeropdk

  • Three submodules:
    • zeropdk.tech: helps load a tech layer definition from a lyp file.
    • zeropdk.layout: a library of tools for advanced polygon creation (round polygons, waveguides, etc).
    • zeropdk.pcell: contains standard class definitions of PCells, ports and parameters. The idea is to make it compatible with SiEPIC-Tools and Klayout Macro Editor (eventually)
  • Similarly to SiEPIC-Tools, zeropdk modifies/patches some Python bindings for klayout objects, such as SimplePolygon, Point, Vector.
  • Beta status: scarce docs (need help!)
In [1]:
!pip install zeropdk
Requirement already satisfied: zeropdk in /Users/tlima/02GitProjects/layout/zeropdk (19.10b0)
Requirement already satisfied: numpy in /Users/tlima/Envs/zeropdk37/lib/python3.7/site-packages (from zeropdk) (1.17.0)
Requirement already satisfied: klayout in /Users/tlima/Envs/zeropdk37/lib/python3.7/site-packages (from zeropdk) (0.26.0.dev16)
Requirement already satisfied: scipy in /Users/tlima/Envs/zeropdk37/lib/python3.7/site-packages (from zeropdk) (1.3.0)
In [4]:
!ls ../demo | grep .lyp

from zeropdk.tech import Tech
EBeam = Tech.load_from_xml('../demo/EBeam.lyp')
EBeam.layers
EBeam.lyp
Out[4]:
{'Si': Si (1/0),
 '31_Si_p6nm': '31_Si_p6nm' (31/0),
 'Text': Text (10/0),
 'Si N': 'Si N' (20/0),
 'Si N++': 'Si N++' (24/0),
 'SEM': SEM (200/0),
 'M1': M1 (41/0),
 '12_M2': '12_M2' (12/0),
 '13_MLopen': '13_MLopen' (13/0),
 'VC': VC (40/0),
 'M Heater': 'M Heater' (47/0),
 'FloorPlan': FloorPlan (99/0),
 'DevRec': DevRec (68/0),
 'PinRec': PinRec (1/10),
 'FbrTgt': FbrTgt (81/0),
 'Errors': Errors (999/0),
 'Lumerical': Lumerical (733/0),
 'Waveguide': Waveguide (1/0)}
In [5]:
import zeropdk.layout.waveguide_rounding as wav_rounding

wav_rounding.main()  # produce some interesting non-Manhattan waveguides
Wrote waveguide_rounding.gds

Contents of waveguide_rounding.gds:

image.png

In [8]:
!python ../demo/main_python.py
Wrote to example_mask.gds
In [9]:
# !open example_mask.gds

image.png

Demo preparation

Two options

1. Your custom python installation

If you have python 3.6+ installed in your computer and are comfortable with installing packages with pip, all we need is pip install zeropdk.

2. Docker Container

For users without Python 3.6+ setup, I have prepared a docker container with all the necessary packages pre-installed. It is compatible with all OS and runs isolated from your installation. I've tested on macOS and Windows 10.

Docker requirements:

Windows Requirements:

  • Windows 10 64-bit: Pro, Enterprise, or Education (Build 15063 or later).
  • Hyper-V and Containers Windows features must be enabled.
  • The following hardware prerequisites are required to successfully run Client Hyper-V on Windows 10:
    • 64 bit processor with Second Level Address Translation (SLAT)
    • 4GB system RAM
    • BIOS-level hardware virtualization support must be enabled in the BIOS settings. For more information, see Virtualization.

macOS Requirements:

  • Mac hardware must be a 2010 or newer model, with Intel’s hardware support for memory management unit (MMU) virtualization, including Extended Page Tables (EPT) and Unrestricted Mode. You can check to see if your machine has this support by running the following command in a terminal: sysctl kern.hv_support

  • macOS must be version 10.13 or newer. We recommend upgrading to the latest version of macOS.

    • If you experience any issues after upgrading your macOS to version 10.15, you must install the latest version of Docker Desktop to be compatible with this version of macOS.
  • At least 4 GB of RAM.
  • VirtualBox prior to version 4.3.30 must not be installed as it is not compatible with Docker Desktop.

Installation Instructions (Simple)

Docker

I have prepared a docker container with all the necessary packages pre-installed. It is compatible with all OS and runs isolated from your installation.

1. Download Docker:

  • macOS
  • Windows download
    • Note: on Windows, the installation will require you to sign out and sign in, so save all your work!

2. Install Docker

The first time you start Docker it will pop up a dialog telling you you need an account. You do not need an account. Close the dialog that tells you this: Docker is already running and fully functional. There are thousands of people complaining about the fact that they try to force you to login in order to download/use it.

3. Pull docker image from docker.io

Open your command line terminal (cmd in Windows) and type:

docker pull felimath/zeropdk

You can check the Docker Image with

docker images

It should show:

REPOSITORY                 TAG                 IMAGE ID            CREATED              SIZE
felimath/zeropdk           latest              1082ad385453        About a minute ago   1.42GB
...

This demo's image id: 1082ad385453.

4. Navigate to the demo folder, downloaded from github.

Download the demo files from the workshop's github repo and navigate to the demo folder.

(Option 1) Using git:

git clone https://github.com/thomaslima/2019-siepic-workshop-zeropdk.git ~/2019-siepic-workshop-zeropdk

If you have cloned the repo, navigate to ~/2019-siepic-workshop-zeropdk/demo with:

cd ~/2019-siepic-workshop-zeropdk/demo

(Option 2) Download zipped file:

If you don't have git (Windows, or any other reason), feel free to download a zip file directly from github. In my computer, I extracted to the default location and used the following command to get there:

# windows
cd Downloads\2019-siepic-workshop-zeropdk-master\2019-siepic-workshop-zeropdk-master\demo

# bash (unix)
cd ~/Downloads/2019-siepic-workshop-zeropdk-master/demo

5. Run the jupyter notebook start script.

From within the demo folder, run the following command in your console

# windows
start-jupyter-windows.bat
# unix
./start-jupyter-unix.sh

image.png

Final step:

Open a browser and go to the highlighted address as shown above. In my case, it was http://127.0.0.1:42019/?token=71e68bae28024c9be4382e6a3f3bd03a0394f678a4e4de2c, but yours will have a different token.

Installation Instructions (Advanced)

Python 3

I write all my scripts using python 3.6+ in mind. I did not pay special attention to backwards compatibility with earlier versions. Fixing syntax bugs should be straightforward if you are experienced with python. If you need to use the packages or demos presented here, feel free to submit a pull request to the relevant repositories.

KLayout

KLayout is an open-source viewer and editor of IC layout files. It has a programming interface with Python and Ruby programming lanaguages. Recently, a pip package was released for the following python distributions:

OS Python Version
macOS 10.11+ 2.7, 3.7
macOS 10.13+ 3.5, 3.6
linux x64, x32 2.7, 3.5, 3.6, 3.6
win32, win64 3.5, 3.6, 3.7

Note for advanced users: You can attempt to build klayout from source by running python setup.py install on the cloned folder from klayout's github repo.

Zeropdk

Zeropdk is a python opensource package with basic tools for photonics layout based on the klayout database engine. It is akin to SiEPIC-tools but it was written so that it could be compatible with any foundry's layer stacks. It can also be installed with pip via pip install zeropdk. Alternatively, install from source via the github repo. Documentation is scarce at the moment but hopefully this workshop will be a good start.

Meta: Adapting the docker container to your demo

If you like Docker and want to build your own Docker image (opensource or closed source), I put the recipe (called Dockerfile) inside the docker-image folder.

Demo 1

Open demo/1. Demo - Using SiEPIC cell library.ipynb

Demo 2

Open demo/2. Demo - MZI PCell.ipynb

Advanced layout techniques

One goal: enable collaboration reduce dependence on a single designer or specific computer setup.

Key questions – recommended tools

What is going on? – Visual debugging

  • Python debugger + inter-process control (github.com/atait/klayout-ipc)

Is it working? – Geometric unit testing

  • KLayout XOR diff program + Pytest (docs.pytest.org)

What if, oops, and collaborating – Version control

  • Git (www.atlassian.com/git/tutorials)

What does this thing do? – Documentation & examples

  • Sphinx (www.sphinx-doc.org)

What parts go where? – Modules, packaging

  • Read and think about it (docs.python-guide.org/writing/structure)

Procedural Layout introduces pitfalls

  • Completely repeatable (but opaque and not interactive)
  • Press a button, GDS comes out
  • Easy to apply global changes (and introduce subtle side-effects)
  • Easy to version and collaborate (and quietly break your friends’ stuff)
  • Full record of design intent (or messy unreadable code)

Powerpoint presentation in person. Might share here later.